AMP Graphics Collection/AMP Graphics Collection.iso/programs/author/versions/readme.mac

Text File | 1996-08-09 | 19KB | 357 lines

Versions XObject for Windows
---------------------------
Version 1.1, 8/9/96
Copyright ⌐ 1996 Glenn M. Picher, Dirigo Multimedia
Email: [e-mail]
Phone: [phone]
Web: http://www.maine.com/shops/gpicher

Distributor of registered version
------------------------------
g/matter, inc.
Email: [e-mail]
Web: http://www.gmatter.com
Phone: [phone]

Detecting version, directory and file information with Versions
---------------------------------------------------------
The Versions XObject for Windows detects QuickTime, DOS, Windows and
file versions. It's able to detect both Win16 and Win32 versions
and directories. It's also able to convert between MS-DOS short
file names and Windows 95 / Windows NT long file names.

You can use the XObject for free to detect QuickTime version numbers
(both for 16-bit QuickTime and 32-bit QuickTime). You'll need to
register the XObject to use any of the other methods without showing
the copyright notice alert box.

The Versions XObject works with both Director 4 and Director 5.
Even when running under Director 4 (always 16-bit) and under
Director 5's 16-bit projectors, or the Director 5's 16-bit authoring
environment, the XObject is able to detect 32-bit version information
by loading a small 32-bit application and 32-bit .DLL file
(included with the XObject, and located in the same directory).

Sample cut-and-paste Lingo handlers are provided in the Director 4
testbed movie that's provided with the XObject (using the method
names without the initial "m", to match exactly the syntax
of global handler names in the planned release of a Lingo Xtra
version duplicating this XObject's functionality). You literally only
need to cut and paste one script castmember and make sure the required
files are in the right directory in order to start using this XObject
immediately. You needn't actually write any Lingo code to interface
with the XObject directly.

The Director 4 testbed movie opens and works fine without modification
in Director 5. In addition to testing all methods, there are also
sample buttons to decide whether to install or update QuickTime; to
check the version number of the appropriate 16-bit or 32-bit version
of the primary Video for Windows file, MSVIDEO.DLL, in the appropriate
System directory; a button to determine the appropriate 32-bit
System directory (which is a different directory that the 16-bit
System directory under Windows NT); and a button to identify
the first shortcut in the Windows 95 Accessories menu (which
demonstrates the short / long file name conversion methods).

This XObject has been tested under Window 3.1, Windows 95 and Windows
NT. The only current limitation is that  Director 5 is not able to use
inherently 16-bit XObjects from 32-bit projectors or the 32-bit
authoring environment under Windows NT; I anticipate releasing an .x32
Lingo Xtra version of this XObject soon to evade that restriction.
This XObject works fine with 16-bit Director 5 projectors, or Director
4's authoring environment and projectors, under Windows NT.
Unfortunately, the 16-bit Director 5 authoring environment doesn't run
under Windows NT, so you have to do your Windows NT authoring on
another non-NT Windows machine if you want to use XObjects with
Director 5.

The Versions XObject's registered version is distributed by
g/matter, inc. in San Francisco. Contact information is above.
Versions is one of several plug-ins that are useful in designing
CDs that install and run automatcially on both Mac and Windows.
Check my Web site again soon for other installation tools.

New version information
-----------------------
Version 1.0 of this XObject checked the 16-bit QuickTime version
within the XObject code itself (i.e., within Versions.DLL). However,
field reports indicated that Director 4 and 16-bit Director 5 would
sometimes get confused about the state of QuickTime (which the
XObject could affect), and would sometimes crash. Therefore,
version 1.1 completely insulates the QuickTime code from the Director
application itself by locating it in Vers16.DLL, which is loaded by
Ask16.EXE when the mQuickTimeVersion method is used. Be sure to
distribute those two additional files when you upgrade to this
version of the XObject.

New to version 1.1 of this XObject are the mGetShortFileName and
mGetLongFileName methods, which allow you to convert between MS-DOS
style '8.3' short file names and Windows 95 / Windows NT style
long file names (which can contain characters such as spaces that
are illegal in MS-DOS filenames). This may be necessary if you're
checking file versions of a known long-name file, or within a
known long-name directory. These methods can also be helpful
when using XObjects that are not aware of and don't work with
long file names.

Also new to version 1.1 is the mWinNTVersion method, which lets
you check whick version of Windows NT your code is running under:
Workstation, Server, or Advanced Server.

mDescribe documentation
-----------------------
Here's the XObject's complete table of methods, which provides some
minimal documentation. This is also available in Director's
Message window, as usual, by sending an mDescribe message to the
name of the XObject factory; that is, by typing...

  Versions(mDescribe)

Versions(mDescribe)
-- Versions XObject, version 1.1, 8/9/96
Versions
-- Copyright ⌐ 1996 Glenn M. Picher, Dirigo Multimedia
-- Email: [e-mail]
-- Web: http://www.maine.com/shops/gpicher
-- Phone: [phone] (South Portland, Maine, USA)
--
-- Distributors: g/matter, inc.
-- Email: [e-mail]
-- Web: http://www.gmatter.com
-- Phone: [phone] (San Francisco, California USA)
--
-- License granted to use and redistribute for any purpose,
-- as long as copyright and contact information remains intact.
-- Each instance of the XObject will present a copyright alert
-- box once if you use any methods other than the QuickTime version
-- checking functions. The registered version does not present any
-- alert boxes.
--
I mNew           -- Standard creation method
X mDispose       -- Standard dispose method
S mQuickTimeVersion
--  Get string of QuickTime version ('000000.000000.000000.000000' if QTW
--  is not installed). Suitable for string comparisons (<, =, >). Example:
--  Your title includes the QTW v2.1.1.57 installer, and you're running on
--  a machine with QTW v2.0.1.41 already installed.  QTW v. 2.1.1.57 becomes
--  '000002.000001.000001.000057' . Alphabetically, this comes after QTW
--  v. 2.0.1.41 ('000002.000000.000001.000041'). Thus you can conclude
--  that QuickTime needs to be updated to the version supplied with your
--  title. This is a workaround for a bug in MCI 'info qtwvideo version'
--  reporting, which does not always produce valid numeric comparisons. Only
--  reports the 16-bit QuickTime version. Works by initializing QuickTime,
--  so the first use may take much longer than subsequent uses.
--  Number is formatted to be compatible with file version numbers.
--  Note: requires ASK16.EXE and VERS16.DLL in the same directory as this
--  XObject .DLL (these files are distributed with this XObject).
--  Returns EMPTY if ASK16.EXE can't load; Returns string with word 1 'Error:'
--  if ASK16.EXE fails. ***Note: version 1.0 of this XObject did not use
--  ASK16.EXE and VERS16.DLL . To avoid occasional crashes when 16-bit Director
--  got confused about the state of QuickTime, this new version keeps
--  Director's QuickTime code isolated from this XObject's QuickTime
--  code. Be sure to add ASK16.EXE and VERS16.DLL to your
--  distributed projects when upgrading to this version of this XObject.
S mWin32QuickTimeVersion
--  Reports the 32-bit QuickTime version. Requires ASK32.EXE and VERS32.DLL
--  in the same directory as this XObject .DLL . These files are
--  distributed with this XObject .DLL file. Returns EMPTY if 32-bit
--  environment is unavailable, or ASK32.EXE can't load; Returns
--  string with word 1 'Error:' if ASK32.EXE fails.
SS mFileVersion, fileName
--  Get string of file version number. Allows checking versions of
--  QuickTime compressor files, even 32-bit versions. Suitable for string
--  comparisons. Example: QTIM32.DLL in the System folder, v. 2.1.1.57 becomes
--  '000002.000001.000001.000057' . The extra digits are the minimum required to
--  represent the maximum 64-bit version number. Can be used with any file that
--  contains a version resource, not just QuickTime files. If file is missing
--  or does not contain version info, result is '000000.000000.000000.000000' .
--  Works whether 32-bit environment is available or not; however,
--  ASK32.EXE and VERS32.DLL are required in the same directory as this
--  XObject .DLL to get Win32 version numbers under Windows NT or 95. These
--  files are distributed with this XObject .DLL file. Further note: Windows
--  NT uses a different system directory for 32-bit .DLLs. See below.
S mWindowsDirectory
--  Returns full path to Windows directory (including trailing '\').
--  Useful for building full path names for use with mFileVersion.
--  Word 1 of the returned string will be 'Error:' in the unlikely
--  event of an error, followed by a description of the error.
--  Note: returns the Win16 answer (see below).
S mWin32WindowsDirectory
--  Returns full path to Windows directory (including trailing '\').
--  Should be the same answer as mWindowsDirectory for all current
--  Windows versions, but this may change in future Win versions.
--  Note: requires ASK32.EXE and VERS32.DLL in the same directory as this
--  XObject .DLL (these files are distributed with this XObject).
--  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
--  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
S mSystemDirectory
--  Returns full path to System directory (including trailing '\').
--  Useful for building full path names for use with mFileVersion.
--  Word 1 of the returned string will be 'Error:' in the unlikely
--  event of an error, followed by a description of the error.
--  Note: returns the Win16 answer (see below).
S mWin32SystemDirectory
--  Returns full path to System directory (including trailing '\').
--  Under Windows NT, this is a different answer than mSystemDirectory.
--  Note: requires ASK32.EXE and VERS32.DLL in the same directory as this
--  XObject .DLL (these files are distributed with this XObject).
--  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
--  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
S mDOSVersion
--  Returns the DOS version reported to 16-bit apps. No Win32 equivalent.
S mWindowsVersion
--  Returns the Windows version reported to 16-bit apps. This is
--  not the same answer as mWin32Version under Windows 95.
S mWin32Version
--  Returns the Win32 version (a different answer than mWindowsVersion)
--  Note: requires ASK32.EXE and VERS32.DLL in the same directory as this
--  XObject .DLL (these files are distributed with this XObject).
--  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
--  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
--  Note the lack of ability to check for Win32-specific DOS version.
S mWin32Platform
--  Returns the Win32 platform ('Win32s on Windows 3.1',
--  'Win32 on Windows 95', or 'Windows NT').
--  Note: requires ASK32.EXE and VERS32.DLL in the same directory as this
--  XObject .DLL (these files are distributed with this XObject).
--  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
--  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
S mWin32Build
--  Returns the Win32 build. This is useful because Director requires
--  at least Windows NT v3.51 with Service Pack 4 applied (build 1057).
--  Note: requires ASK32.EXE and VERS32.DLL in the same directory as this
--  XObject .DLL (these files are distributed with this XObject).
--  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
--  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
S mWinNTVersion
--  Tells you what verison of Windows NT you're running under-- 'Workstation',
--  'Server', 'Advanced Server', 'Unknown', or 'Error' is there's a problem.
--  Note: requires ASK32.EXE and VERS32.DLL in the same directory as this
--  XObject .DLL (these files are distributed with this XObject).
--  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
--  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
SS mGetShortFileName, theFile
--  Returns the MS-DOS style filename of a Windows 95 or Windows NT long
--  file name which might contain spaces or other DOS-illegal characters.
--  This method can also accept file names that are already DOS-legal.
--  This method is helpful when an XObject only works with DOS filenames.
--  Note: requires ASK32.EXE and FNAME32.DLL in the same directory as this
--  XObject .DLL (these files are distributed with this XObject).
--  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
--  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
SS mGetLongFileName, theFile
--  Returns the Windows 95 or Windows NT long file name, which might contain
--  spaces or other DOS-illegal characters, given a DOS short file name.
--  This method can also accept file names that are already long.
--  Note: requires ASK32.EXE and FNAME32.DLL in the same directory as this
--  XObject .DLL (these files are distributed with this XObject).
--  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
--  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
--

Of historical interest: Why the Versions XObject?
--------------------------------------------
Initially, the Versions XObject was created to work around a bug in the
MCI interface to QuickTime for Windows. When requesting QuickTime version
numbers using...

    mci "info qtwvideo version"
    put the result

...the reported number would not report decimal point placement
consistently across different version of QuickTime for Windows. This made
it rather difficult to determine whether the user should update QuickTime
with the version of the QuickTime for Windows installer you provided with
your title.

However, the question of version numbers proved more subtle with Apple's
introduction of 16-bit and 32-bit flavors of QuickTime for Windows
beginning with version 2.1.1 in the spring of 1996. It's only possible
to detect the 16-bit QuickTime version from a 16-bit app or .dll, and
you can only know the 32-bit QuickTime version from a 32-bit app or
.dll . XObjects are inherently 16-bit code, and so always return a
16-bit answer to questions such as these. To make things more confusing,
the MCI interface to QuickTime for Windows could report a 16-bit version
number to a 32-bit application (Director 5), even though the application,
using the C rather than the MCI interface to QuickTime, required the
32-bit version.

The mFileVersion method was intended to work around this limitation by
checking for a file version resource in particularly named files in the
System directory (such as QTIM32.DLL). However, there are a number of
problems with this approach. The existence of a file alone does not
confirm proper configuration. Furthermore, certain .DLLs have file
version resources that can only be read from 32-bit code running on a
32-bit platform (such as WIndows NT system files); they can't be
identified from 16-bit code. Finally, Windows NT places 32-bit .DLL
files into a different directory than 16-bit .DLLs, and the name of that
directory can only be detected from 32-bit code.

The solution was to write a 32-bit application which called a 32-bit
.DLL to get 32-bit answers to these configuration questions. This 32-bit
application (Ask32.exe) is launched by the 16-bit XObject .DLL file, and
the two tasks communicate with each other to access the requested
information.  Ask32.exe and Vers32.dll must be distributed in the same
directory as Versions.dll to work properly on Win32 platforms such as
Windows 95 and Windows NT.


Known bugs:
-----------
None.

Known limitations:
------------------
Does not operate under Windows NT with 32-bit Director 5's authoring
environment or Director 5's 32-bit projector. This is true of any
XObject.

This XObject should be used in an initial Director movie that does *not*
contain any QuickTime castmembers. Director itself will display an
ungraceful message about the need for QuickTime when a movie is
loaded, if any QuickTime castmember are found in the movie, *before*
you get a chance to use the Versions XObject.

The QuickTime version methods are rather slow, because not only
do they fully initialize QuickTime and all its .DLL files, but
the code itself is run from a separate .EXE file loaded by this
XObject. Little can be done to speed this process up.

Revision history:
-----------------
8/9/96: Version 1.1
    Isolated QuickTime code from Director's code in mQuickTimeVersion
    method by using Ask16.EXE and Vers16.DLL . This eliminates some
    confusion and possible crashes when Versions was used from 16-bit
    Director executables.

    Added mGetShortFileName, mGetLongFileName, and mWinNTVersion
    methods.

    Added more information to Read Me document.

6/26/96: Version 1.0
    16 and 32 bit methods.

6/8/96: Version 0.9 beta
    16-bit only methods.

Standard legal disclaimer
-------------------------
This software is provided "as is" without warranty of any kind, either
expressed or  implied, including, but not limited to, the implied
warranties of merchantability or fitness for a particular purpose.
The software or its documentation or sample code may include errors
or technical inaccuracies. Changes are periodically made to this
software, its documentation and sample code, and may be incorporated
in new versions. Dirigo Multimedia and g/matter may improve or
change their products at any time without notice.  Dirigo Multimedia
and g/matter assume no responsibility for and disclaim all
liability for errors in this software or its documentation and sample
code.  Neither Dirigo Multimedia nor g/matter will be responsible for
any damages of any sort under any conditions. While the Versions
XObject contains no known bugs, use it at your own risk. As always,
you should make frequent backups of important information.
Some jurisdictions do not allow the exclusion of implied
warranties, so the above exclusion may not apply to you.